I recently downloaded the most recent version of Doxygen to document my DXL. Setting the language to C, it seems to parse 'if' statements as functions, which make the documentation really untidy. e.g: Functions:
if (null(objectEditingFilteringToolCurrentModule)) Is this normal behaviour, or is there a setting that I'm missing? Unfortunately, Mathias' example project attachment in the following topic is un-zip-able for me, so can't investigate that:
7XUT_Antonio_Norkus - Thu Aug 21 09:21:25 EDT 2014 |
Re: DXL Doxygen - should 'if' statements be parsed as functions?
I don't have an installation of doxygen at hand and cannot test, but attached is the file from Mathias, zipped in another format. (7-zip would also have helped to unzip the file)
hope this helps, Attachments attachment_14414463_DXL_Documentation.zip |
Re: DXL Doxygen - should 'if' statements be parsed as functions? Hi In Dxl you can write if (null(objectEditingFilteringToolCurrentModule)) print "Yes"; or you can write
if (null(objectEditingFilteringToolCurrentModule)) { print "Yes" };
In the first case Doxygen interprets if as a function in the second case it does not. You have to use {} in any cases. Best regards Wolfgang |
Re: DXL Doxygen - should 'if' statements be parsed as functions? Wolfgang Uhr - Wed Aug 27 13:44:52 EDT 2014 Hi In Dxl you can write if (null(objectEditingFilteringToolCurrentModule)) print "Yes"; or you can write
if (null(objectEditingFilteringToolCurrentModule)) { print "Yes" };
In the first case Doxygen interprets if as a function in the second case it does not. You have to use {} in any cases. Best regards Wolfgang Thanks for you inpu Wolfgang, but it doesn't appear that it is a case of ensuring that 'if' statement blocks need to be in braces.
The following code is interpreted as a function:
Module funcResponsibilitiesModule = read((fullName(funcResponsibilitiesModRef)), false);
if (null(funcResponsibilitiesModule))
{
errorBox("Failed to open the \"Functional Responibilities\" module for your project.\n\nPlease seek assistance from your DOORS Administrator.");
halt();
}
|
Re: DXL Doxygen - should 'if' statements be parsed as functions? 7XUT_Antonio_Norkus - Thu Aug 28 08:03:20 EDT 2014 Thanks for you inpu Wolfgang, but it doesn't appear that it is a case of ensuring that 'if' statement blocks need to be in braces.
The following code is interpreted as a function:
Module funcResponsibilitiesModule = read((fullName(funcResponsibilitiesModRef)), false);
if (null(funcResponsibilitiesModule))
{
errorBox("Failed to open the \"Functional Responibilities\" module for your project.\n\nPlease seek assistance from your DOORS Administrator.");
halt();
}
Have you tried adding semicolons to make the code look more like C? Tony |
Re: DXL Doxygen - should 'if' statements be parsed as functions? Tony_Goodman - Thu Aug 28 09:47:15 EDT 2014 Have you tried adding semicolons to make the code look more like C? Tony Hi Tony....I've tried that...is there a problem in the semi-coloning of my code snippet? |
Re: DXL Doxygen - should 'if' statements be parsed as functions? 7XUT_Antonio_Norkus - Tue Sep 02 08:53:49 EDT 2014 Hi Tony....I've tried that...is there a problem in the semi-coloning of my code snippet? Probsbly some setting in your Doxyfile is incorrect. I am not sure what Matthias did to doxygen to create dxl_doxygen. My impression was that all you have to do is set up your dxl extensions to be interpreted interpreted as C. I have the following in my doxyfile
EXTENSION_MAPPINGS = .inc=C \ .dxl=C \ .dxf=C \ .man=C
Not sure what you mean about if statements being parsed as functions. Doxygen only processes comments in a particular style, if there are no comments you can choose not to produce any documentation for them - maybe you could try that - pretty sure I didn't have to ansd I have plenty of if statements. Probably the way you are commenting your functions - try using qt style like the following
/*!
\brief Need to push all the modules in a folder (recursively into the passed skip list
\param thisFolder The name of the folder that is to be processed
\param thisSkip Skip that the values are to be added to
\param wantLinkMods whether to process link or formal modules
*/
void folderRecurseForScope(string thisFolder, Skip thisSkip, bool wantLinkMods) {
Hope that gives you a clue! Richard
|
Re: DXL Doxygen - should 'if' statements be parsed as functions? Richard_Good - Wed Sep 10 08:16:59 EDT 2014 Probsbly some setting in your Doxyfile is incorrect. I am not sure what Matthias did to doxygen to create dxl_doxygen. My impression was that all you have to do is set up your dxl extensions to be interpreted interpreted as C. I have the following in my doxyfile
EXTENSION_MAPPINGS = .inc=C \ .dxl=C \ .dxf=C \ .man=C
Not sure what you mean about if statements being parsed as functions. Doxygen only processes comments in a particular style, if there are no comments you can choose not to produce any documentation for them - maybe you could try that - pretty sure I didn't have to ansd I have plenty of if statements. Probably the way you are commenting your functions - try using qt style like the following
/*!
\brief Need to push all the modules in a folder (recursively into the passed skip list
\param thisFolder The name of the folder that is to be processed
\param thisSkip Skip that the values are to be added to
\param wantLinkMods whether to process link or formal modules
*/
void folderRecurseForScope(string thisFolder, Skip thisSkip, bool wantLinkMods) {
Hope that gives you a clue! Richard
My doxygen is currently experimental...I haven't added any doxygen documentation comments to the code. All I have done is: - taken a small subset of my code base - ensured the subset is semicoloned and ensured that all functions with zero or one parameter has the function parenthesis added. - added .dxl and .inc suffixes as C files - generated all documentation in doxygen
The result is that, for each 'if' statement in the code, I get a "Documentation for function 'if'" result in the generated documentation. In Matthias' example, it only generates documentation for items containing doxygen documentation comments, so the 'if' statements are not reaching the documentation. At this early stage, I don't want a decent doxygen output to be dependent upon the addition of doxygen documentation comments to the code (I haven't the time/resource to do that). I just want a raw documentation of the code structure and include file structure, so that the usage of library functions is displayed in the documentation. This problem with doxygen producing documentation for 'if' statements, is that it is messing up the raw documentation of the code, as lots of superfluous "Documentation for function 'if'" items are created in the documentation, along with the generation of 'if' function call and caller graphs. I hope this clarifies my problem. |
Re: DXL Doxygen - should 'if' statements be parsed as functions? 7XUT_Antonio_Norkus - Wed Sep 10 09:09:13 EDT 2014 My doxygen is currently experimental...I haven't added any doxygen documentation comments to the code. All I have done is: - taken a small subset of my code base - ensured the subset is semicoloned and ensured that all functions with zero or one parameter has the function parenthesis added. - added .dxl and .inc suffixes as C files - generated all documentation in doxygen
The result is that, for each 'if' statement in the code, I get a "Documentation for function 'if'" result in the generated documentation. In Matthias' example, it only generates documentation for items containing doxygen documentation comments, so the 'if' statements are not reaching the documentation. At this early stage, I don't want a decent doxygen output to be dependent upon the addition of doxygen documentation comments to the code (I haven't the time/resource to do that). I just want a raw documentation of the code structure and include file structure, so that the usage of library functions is displayed in the documentation. This problem with doxygen producing documentation for 'if' statements, is that it is messing up the raw documentation of the code, as lots of superfluous "Documentation for function 'if'" items are created in the documentation, along with the generation of 'if' function call and caller graphs. I hope this clarifies my problem. There are many many settings you can tweak in the dxyfile you use with doxygen. My usage of doxygen goes back at least 5 years so I forget why I arrived at what ever set I arrived at, the attached file represents the most verbose output I produce. Note I use graphviz to produce dependency graphs and microsoft help compiler to produce chm output. You will need to change a number of settings for your environment. Doxygen takes a little while to get your head around, but for me has been well worth the effort. I use doxygen 1.7.1 and graphviz 2.32 Attachments Dxyfile.devRmg |
Re: DXL Doxygen - should 'if' statements be parsed as functions? Richard_Good - Wed Sep 10 09:45:51 EDT 2014 There are many many settings you can tweak in the dxyfile you use with doxygen. My usage of doxygen goes back at least 5 years so I forget why I arrived at what ever set I arrived at, the attached file represents the most verbose output I produce. Note I use graphviz to produce dependency graphs and microsoft help compiler to produce chm output. You will need to change a number of settings for your environment. Doxygen takes a little while to get your head around, but for me has been well worth the effort. I use doxygen 1.7.1 and graphviz 2.32 I think I know where the problem lies. In C, you would never see an 'if' statement at the top-most context. It would always be: - within a "void main(void)" function - within a sub-function. I think the fact that a DXL file can have statements in the top-most context is confusing doxygen, so it processes them as a function. I notice that any 'if' statements within a function are not processed as a function. This makes me unhappy, as many of my "menu item" dxl is expressed at the top-most context :( |
Re: DXL Doxygen - should 'if' statements be parsed as functions? 7XUT_Antonio_Norkus - Wed Sep 10 10:02:07 EDT 2014 I think I know where the problem lies. In C, you would never see an 'if' statement at the top-most context. It would always be: - within a "void main(void)" function - within a sub-function. I think the fact that a DXL file can have statements in the top-most context is confusing doxygen, so it processes them as a function. I notice that any 'if' statements within a function are not processed as a function. This makes me unhappy, as many of my "menu item" dxl is expressed at the top-most context :( You may well be right I almost always use a "Main" function, because that is what prefer/ seems neater. You may well have to change your habits a little to make best use of Doxygen, my .dxl files tend to be short and represent wrappers or guis these may have global variables, most of the logic/ functions are in include files, which tend not to have global variables to avoid dxl traps ;-) |
Re: DXL Doxygen - should 'if' statements be parsed as functions? 7XUT_Antonio_Norkus - Wed Sep 10 10:02:07 EDT 2014 I think I know where the problem lies. In C, you would never see an 'if' statement at the top-most context. It would always be: - within a "void main(void)" function - within a sub-function. I think the fact that a DXL file can have statements in the top-most context is confusing doxygen, so it processes them as a function. I notice that any 'if' statements within a function are not processed as a function. This makes me unhappy, as many of my "menu item" dxl is expressed at the top-most context :( Hi You are right, thats an other problem. Actually I do not have this type of code.
void solveThisProblem () {
// Here is the code
}
solveThisProblem()
I use this structure in any of my projects - for years - and sorry, I've forgotten to list this point here. Best regards Wolfgang |